MARXMENU DATABASE FUNCTIONS

Well, after talking about it for years, version 2.42 now includes a
strong set of database tools. The database is based on Novell's Btrieve
interface. Thus it has the reliability of proven database technology. We
are pushing Btrieve to the limit and then some in order to get the
requirements needed from a database engine.

As of version 2.42 about 90% of the features of Btrieve have been
implemented in MarxMenu. So if you are familiar with Btrieve
already you will be able to do most things just like you're used to.

Btrieve is primarily a fixed length database engine with the ability to
add a single variable length field on the end of a record. When using
MarxMenu with Btrieve, we typically store MarxMenu style variables in
the variable length section and reserve the fixed length section for key
fields only. While we recommend you too consider this approach you are
free to develop and use any data models you prefer.

You will notice several unusual things about MarxMenu as a database.
We decided that the square model or relationally linked square model is
to limiting. You can do square model databases if you want to, but the
experience of getting rid of the square model is like an animal being
let out of a cage for the first time. It's a little scary at first.

When you create a MarxMenu Btrieve database you may define all your
fields, if you want, but you are only required to define the fields that
will be used as key fields. You will need to define the fields type, and
for key fields the key properties.

When data is written to a file the data is passed as a MarxMenu array.
The first elements of the array have to match the fixed potion of you
structure, normally your key fields. Any elements after the key fields
are written in MarxMenu format to the variable length section of the
record. Thus after the key fields you can do whatever you want. Here's a
list of some of the flexible features.

 1) Records do not have to contain the same fields or the same number of
    fields. You can have 20 fields in one record and 5 fields in the
    next one. There are no rules that the data in one field of a record
    has to be of the same data type as the same field of the previous
    record.

 2) Records can contain MarxMenu style arrays. Thus if you are using a
    phone field as an array of phone numbers you can store as many phone
    numbers in that field as you want. MarxMenu can support arrays
    within arrays of up to 30 levels within a single record.

 3) Since MarxMenu supports writing MarxMenu style variable structures
    to database records, you need not have to specify the type of data,
    the data size, or the structure of the data before you access the
    file. If you want to write data you just do it.

Since this code is new you may want a lot of new features added to go
along with what's provided so far. Feel free to call with suggestions,
we are interested in hearing how this is working out for you.

Use of the Btreive commands require that you have Btrieve 6.0 or 5.10.
You will need to have Btrieve NLM running on the server and BRequest
running on the workstation to use this database. All the Btreive
database commands start with the BTRV prefix.

Only network versions of MarxMenu contain the BTRV database commands,
the single user version is not equiped with this feature.


BtrvAbortTransaction
BtrvAbortTransaction is used to about all changes to the file that have
occurred since the BtrvBeginTransaction was executed.

See Also: BtrvBeginTransaction, BtrvEndTransaction

Category: Btrieve


BtrvBeginTransaction
Betrieve supports a concept called transaction tracking. With
transaction tracking you can use the BtrvBeginTransaction command to set
a file condition flag marking the start of a file process. Should the
file process be interupted before the end of the process the files will
be restored to the original condition they were in prior to the
BtrvBeginTransaction.

See Also: BtrvAbortTransaction, BtrvEndTransaction

Category: Btrieve


BtrvClearOwner (Handle)
BtrvClearOwner clears the owner and allows normal access to the file.

 Example:
   BtrvClearOwner (Handle)

See Also: BtrvSetOwner

Category: Btrieve


BtrvClose (Handle)
BtrvClose closes the file. The parameter `Handle' is the file handle
returned from BtrvOpen.

 Example:
   BtrvClose (Handle)

See Also: BtrvOpen

Category: Btrieve


BtrvCreate (FileName,Fields)
BtrvCreate is the most complicated Btrieve call. It defines the creation
of the Btrieve database. The fields parameter is a two dimensional
MarxMenu array that describes the fields in the file. It is designed to
support either standard Btrieve fixed length fields or MarxMenu key
fields. Using MarxMenu fields is the easiest because you only have to
define the key fields.  Non-Key fields do not have to be predefined.

The easiest way to define these fields is to create a comma delimited
text file and use ReadAscTextFile('FIELDS.TXT',Fields). This will create
the array needed by BtrvCreate. The text file might look as follows:

   Name,String,35,Key,DUP,MOD,UPPER,DEC
   CustomerNumber,Auto
   From,String,35
   Password,String,15
   Access,Num
   Flags,String,10
   FirstDate,Date
   LastDate,Date
   Calls,Num
   CallTime,Time
   Phone,String,15

 Example:
   ReadAscTextFile('FIELDS.TXT',Fields)
   BtrvCreate('BBSUSER.BTD',Fields)

The above example creates a conventional fixed length database with one
key field, the "name" field. Each line in the defination file defines a
new field. Each line has at least two parameters. The first parameter is
the field name. It is followed by the field type. There are five legal
field types.  They are:

  String - Containes alphanumeric strings. String fields have a required
           third parameter, the maximum length of the string. In the
           above example the "Name" and "From" fields both have max
           lengths of 35 characters.

  Num    - Integer numeric fields. This field type supports storing
           integer numbers.

  Date   - Dates fields. The DOS country code is automatically supported
           to establish date format. If not specified, the default
           format is "MM/DD/YY".

  Time   - Time fields. This command also reads the DOS country code to
           establish the proper format.  Otherwise default is "HH:MM:SS".

  Auto   - Auto increment fields. This field is used to maintain field
           counters. This field is more complicated than most. Normally
           in your record mask you should provide a value of zero, this
           will cause the value stored in the file to be one more than
           the value stored in the last record. You can, however,
           provide a mask containing a specific number. If that number
           does not already exist anywhere in this field then it will be
           stored. If it does exist, a Btreive error will result.


USING KEY FIELDS

Key fields are fields that are have internal lookup indexs automatically
defined and maintained by the Btreive system. If you want to use the
intelligent loopup `BtrvGet_____' series of commands then the field you
reference must be a key field. You define a key field by adding the
parameter "KEY" as the third parameter on the field defination line.
When specifying a field as a key field you have four optional
configuration parameters, as seen in the previous example. They are:

  DUP  - {Duplicates}  This permits the field to have duplicate values
         in multiple records. If this parameter is not specified then no
         two records may have the same value in the affected field. In
         reality, you will almost always specify this parameter when
         defining a key field.

  MOD  - {Modifyable}  This allows existing existing field records to be
         modifyed. If this parameter is not specified then once a record
         is written, the affected field is set in stone and changes are
         not permitted.

  UPPER- {UpperCase Only}  Used in cunjunction with string fields only,
         this will force all text information to be stored as UPPERCASE.

  DEC  - {Decending Order}  This caused the key stored in the affected
         field to be maintained in reverse order.


If you wanted to use a MarxMenu style database then only the first line
of the above example need be in the file. This would create a file with
a single fixed length key field and put the rest of the fields in the
variable length section. Using the MarxMenu style you can pass anything
you want for the rest of the fields.

Category: Btrieve


BtrvDelete (Handle)
BtrvDelete deletes a record from a data file at the location of the last
data read from the file.

 Example:
   BtrvGetEqual(DataVar,'MARC PERKEL',1,Handle)
   BtrvDelete(Handle)

See Also: BtrvInsert

Category: Btrieve


BtrvEndTransaction
BtrvEndTransaction is used at the end of a transaction tracking process.
This command updates the files with all the data to be written. Refer to
the BtrvBeginTransaction command for additional information.

See Also: BtrvAbortTransaction, BtrvBeginTransaction

Category: Btrieve


BtrvGetEqual (DataVar,Value,Key,Handle)
BtrvGetEqual goes to the previous record of the file based on the key
number that you pass and reads the record matching Value into DataVar.
The type of Value passed has to match the type of data the key for which
the key is defined. If the key is a string then Value is a string. If
BtrvResult is zero, the data was found. If BtrvGetNext is called after
this, the next sequential record based on the key is read.

 Example:
   BtrvGetEqual(DataVar,'MARC PERKEL',1,Handle)

See Also: BtrvGetLess, BtrvGetLessOrEqu, BtrvGetGreater
See Also: BtrvGetGreaterOrEqu

Category: Btrieve


BtrvGetFirst (DataVar,Key,Handle)
BtrvGetFirst goes to the first record of the file based on the key
number that you pass and reads the record into DataVar. This allows you
to access that database in the sorted order of the key. DataVar is a
MarxMenu variable and the data read creates an array of the fields
stored on disk.

 Example:
   ReadAscTextFile('FIELDS.TXT',Fields)
   Handle = BtrvOpen('BBSUSER.BTD',Fields)

   BtrvGetFirst(DataVar,1,Handle)
   while BrtvResult = 0
      loop DataVar
         Write DataVar[LoopIndex] ' '
      endloop
      Writeln
      BtrvGetNext(DataVar,1,Handle)
   EndWhile

This example dumps the contents of a file to the screen.

See Also: BtrvGetLast, BtrvGetNext, BtrvGetPrev

Category: Btrieve


BtrvGetGreater (DataVar,Value,Key,Handle)
BtrvGetGreater goes to the next larger record of the file based on the
key number that you pass and reads the record greater than Value into
DataVar. The type of Value passed has to match the type of data the key
for which the key is defined. If the key is a string then Value is a
string. If BtrvResult is zero, the data was found. If BtrvGetPrev is
called after this, the next sequential record based on the key is read.

 Example:
   BtrvGetLess(DataVar,'MARC PERKEL',1,Handle)

See Also: BtrvGetEqual, BtrvGetLess, BtrvGetLessOrEqu
See Also: BtrvGetGreaterOrEqu

Category: Btrieve


BtrvGetGreaterOrEqu (DataVar,Value,Key,Handle)
BtrvGetGreaterOrEqu goes to the next larger or equal record of the file
based on the key number that you pass and reads the record greater than
or equal to Value into DataVar. The type of Value passed has to match
the type of data the key for which the key is defined. If the key is a
string then Value is a string. If BtrvResult is zero, the data was
found. If BtrvGetPrev is called after this, the next sequential record
based on the key is read.

 Example:
   BtrvGetLessOrEqu(DataVar,'MARC PERKEL',1,Handle)

See Also: BtrvGetEqual, BtrvGetLess, BtrvGetLessOrEqu, BtrvGetGreater

Category: Btrieve


BtrvGetLast (DataVar,Key,Handle)
BtrvGetLast goes to the last record of the file based on the key number
that you pass and reads the record into DataVar. This allows you to
access that database in the sorted order of the key. DataVar is a
MarxMenu variable and the data read creates an array of the fields
stored on disk.

 Example:
   ReadAscTextFile('FIELDS.TXT',Fields)
   Handle = BtrvOpen('BBSUSER.BTD',Fields)

   BtrvGetLast(DataVar,1,Handle)
   while BrtvResult = 0
      loop DataVar
         Write DataVar[LoopIndex] ' '
      endloop
      Writeln
      BtrvGetPrev(DataVar,1,Handle)
   EndWhile

This example dumps the contents of a file to the screen backwards.

See Also: BtrvGetFirst, BtrvGetNext, BtrvGetPrev

Category: Btrieve


BtrvGetLess (DataVar,Value,Key,Handle)
BtrvGetLess goes to the next smaller record of the file based on the key
number that you pass and reads the record less than Value into DataVar.
The type of Value passed has to match the type of data the key for which
the key is defined. If the key is a string then Value is a string. If
BtrvResult is zero, the data was found. If BtrvGetPrev is called after
this, the next sequential record based on the key is read.

 Example:
   BtrvGetLess(DataVar,'MARC PERKEL',1,Handle)

See Also: BtrvGetEqual, BtrvGetLessOrEqu, BtrvGetGreater
See Also: BtrvGetGreaterOrEqu

Category: Btrieve


BtrvGetLessOrEqu (DataVar,Value,Key,Handle)
BtrvGetLessOrEqu goes to the next smaller or equal record of the file
based on the key number that you pass and reads the record less than or
equal to Value into DataVar. The type of Value passed has to match the
type of data the key for which the key is defined. If the key is a
string then Value is a string. If BtrvResult is zero, the data was
found. If BtrvGetPrev is called after this, the next sequential record
based on the key is read.

 Example:
   BtrvGetLessOrEqu(DataVar,'MARC PERKEL',1,Handle)

See Also: BtrvGetEqual, BtrvGetLess, BtrvGetGreater, BtrvGetGreaterOrEqu

Category: Btrieve


BtrvGetNext (DataVar,Key,Handle)
BtrvGetNext goes to the next record of the file based on the key number
that you pass and reads the record into DataVar. This allows you to
access that database in the sorted order of the key. DataVar is a
MarxMenu variable and the data read creates an array of the fields
stored on disk.

See Also: BtrvGetFirst, BtrvGetLast, BtrvGetPrev

Category: Btrieve


BtrvGetPrev (DataVar,Key,Handle)
BtrvGetPrev goes to the previous record of the file based on the key
number that you pass and reads the record into DataVar. This allows you
to access that database in the sorted order of the key. DataVar is a
MarxMenu variable and the data read creates an array of the fields
stored on disk.

See Also: BtrvGetFirst, BtrvGetLast, BtrvGetNext

Category: Btrieve


BtrvIndexes (Handle) : Number
BtrvIndexes returns the number of key fields in a file. You must open
the file and get a file handle first.

 Example:
   Writeln BtrvIndexes (Handle)

Category: Btrieve


BtrvInsert (DataVar,Handle)
BtrvInsert adds a new record to the data file. The data is passed in the
array DataVar. If key fields are used, or if you are using traditional
style fixed length fields, then the first elements of the array must
match the data structure of the file you defined with BtrvCreate. All
elements of the array after these fields are written to the variable
length part of the file. The variable length part can contain MarxMenu
multi-dimensional data structures.

 Example:
   BtrvInsert(DataVar,Handle)

See Also: BtrvDelete

Category: Btrieve


BtrvOpen (FileName,Fields) : Handle
BtrvOpen is used to open the file for access. Since Btrieve files do not
store a list of fields you have to pass the same data structure you did
when you created the file. If successful, BtrvOpen will return a file
handle. This handle will be referenced by all other commands that access
this file.

 Example:
   ReadAscTextFile('FIELDS.TXT',Fields)
   Handle = BtrvOpen('BBSUSER.BTD',Fields)
   If BtrvResult<>0
        WriteLn "Btrieve Error: " BtrvResult " While Opening File."
   EndIf

See Also: BtrvClose, BtrvCreate

Category: Btrieve


BtrvPageSize (Handle) : Number
BtrvPageSize returns the page size of in a file. You must open the file
and get a file handle first. The page size is the amount of disk space
allocated when a file is extended.

 Example:
   Writeln BtrvPageSize (Handle)

Category: Btrieve


BtrvRecLen (Handle) : Number
BtrvRecLen returns the size of the fixed length part of in a file. You
must open the file and get a file handle first.

 Example:
   Writeln BtrvRecLen (Handle)

Category: Btrieve


BtrvRecords (Handle) : Number
BtrvRecords returns the number of records in a file. You must open the
file and get a file handle first.

 Example:
   ReadAscTextFile('FIELDS.TXT',Fields)
   Handle = BtrvOpen('CLIENTS.BTR',Fields)
   Writeln BtrvRecords (Handle)           ;# of Records in CLIENTS.BTR

Category: Btrieve


BtrvReset
BtrvReset is used to clear all transactions and close all files. It's a
good idea to start your programs with this command to clear any locks
that might be left out there from other programs that might have
aborted.

 Example:
   var fields

   btrvreset                           ;Start with a clean slate!
   readasctextfile('db.txt',fields)    ;Get field Definitions
   btrvcreate('phone.mb',fields)       ;Create Btrieve File
   writeln btrvresult                  ;Check for ok

Category: Btrieve


BtrvResult : Number
BtrvResult returns the result code from the last Btrieve call. A zero is
considered a success.

 Example:
   Procedure BtrieveError
     If BtrvResult <> 0
       Writeln 'Btrieve Error #',BtrvResult
       Writeln 'Exiting Program...'
       ExitMenu
     EndIf
   EndProc

See Also: BtrvResultMessage

Category: Btrieve


BtrvResultMessage : String
BtrvResultMessage automatically returns a string containing an error
message based on the value BtrvResult.

 Example:
   Writeln BtrvResultMessage          ;write Btreive Error Message

See Also: BtrvResult

Category: Btrieve


BtrvSetOwner (Owner,Mode,Handle)
BtrvSetOwner is really a set password function. It restricts access to
the file unless you pass the owners name by setting BtrvOwner. The mode
controls access and data encryption as follows:

   0 : No Btreive access - File Not Encrypted
   1 : Read Only access  - File Not Encrypted
   2 : No Btreive access - File Encrypted
   3 : Read Only access  - File Encrypted

 Example:
   BtrvSetOwner('NERD',3,Handle)

See Also: BtrvClearOwner

Category: Btrieve


BtrvStepFirst (DataVar,Handle)
BtrvStepFirst goes to the first physical record of the file and reads
the record into DataVar. DataVar is a MarxMenu variable and the data
read creates an array of the fields stored on disk.

 Example:
   ReadAscTextFile('FIELDS.TXT',Fields)
   Handle = BtrvOpen('BBSUSER.BTD',Fields)

   BtrvStepFirst(DataVar,Handle)
   while BrtvResult = 0
      loop DataVar
         Write DataVar[LoopIndex] ' '
      endloop
      Writeln
      BtrvStepNext(DataVar,Handle)
   EndWhile

This example dumps the contents of a file to the screen.

See Also: BtrvStepLast, BtrvStepNext, BtrvStepPrev

Category: Btrieve


BtrvStepLast (DataVar,Handle)
BtrvStepLast goes to the last physical record of the file and reads the
record into DataVar. DataVar is a MarxMenu variable and the data read
creates an array of the fields stored on disk.

 Example:
   ReadAscTextFile('FIELDS.TXT',Fields)
   Handle = BtrvOpen('BBSUSER.BTD',Fields)

   BtrvStepLast(DataVar,Handle)
   while BrtvResult = 0
      loop DataVar
         Write DataVar[LoopIndex] ' '
      endloop
      Writeln
      BtrvStepPrev(DataVar,Handle)
   EndWhile

This example dumps the contents of a file to the screen backwards.

See Also: BtrvStepFirst, BtrvStepNext, BtrvStepPrev

Category: Btrieve


BtrvStepNext (DataVar,Handle)
BtrvStepNext goes to the next physical record of the file and reads the
record into DataVar. DataVar is a MarxMenu variable and the data read
creates an array of the fields stored on disk.  This is normally used to
work through a file when the search field in not a key field.

 Example:
   var fields,temp,handle,vararray
   readasctextfile('data.txt',fields)
   handle=btrvopen('phone.mxb',fields)
   while btrvresult=0
      btrvstepnext(vararray,handle)       ;<- Step to next file record
      writeln vararray[1] " " vararray[2]
   endwhile
   btrvclose(handle)

See Also: BtrvStepFirst, BtrvStepLast, BtrvStepPrev

Category: Btrieve


BtrvStepPrev (DataVar,Handle)
BtrvStepPrev goes to the previous physical record of the file and reads
the record into the variable DataVar. DataVar is a MarxMenu variable and
the data read creates an array of the fields stored on disk.

See Also: BtrvStepFirst, BtrvStepLast, BtrvStepNext

Category: Btrieve


BtrvStop
BtrvStop is used to unload BTRIEVE.EXE or BREQUEST.EXE from memory. You
can load the requestor before running MarxMenu as a database and unload
the requestor when you are finished. This reclaims the memory the
requestor was using.

Category: Btrieve


BtrvUnusedPages (Handle) : Number
BtrvUnusedPages returns the number of unused pages in a file. You must
open the file and get a file handle first. Unused pages are created when
data is deleted from a file.

 Example:
   Writeln BtrvPageSize (Handle)

Category: Btrieve


BtrvUpdate (DataVar,Handle)
BtrvUpdate changes a record in the data file at the last location
accessed with any command that reads a record. The data is passed in the
array DataVar. If key fields are used, or if you are using traditional
style fixed length fields, then the first elemebts of the array must
match the data structure of the file you defined with BtrvCreate. All
elements of the array after these fields are written to the variable
length part of the file. The variable length part can contain MarxMenu
multi-dimensional data structures.

 Example:
   BtrvGetEqual(DataVar,'MARC PERKEL',1,Handle)
   if BtrvResult = 0
      DataVar[3] = 37
      BtrvUpdate(DataVar,Handle)
   endif

Category: Btrieve


BtrvVersion : Number
BtrvVersion returns a number representing the version number of Btrieve
that you are using. A zero indicates that Btrieve is not installed. If
Btrieve is installed then it returns 100 times the version number plus
the minor version number. Version 6.0 becomes 600. Version 5.10 becomes
510.

 Example:
   if BtrieveVersion = 0
      Writeln "Sorry, but Btrieve must be loaded first!"
   else
      Writeln "You are running Btrieve Version #: " BtrvVersion
   endif

Category: Btrieve